What is type-fest?
The type-fest package provides a collection of essential TypeScript types for use in a wide range of applications. It includes utility types, primitive types, and complex object types to enhance TypeScript's static typing capabilities.
What are type-fest's main functionalities?
Primitive types
Includes types like LiteralUnion, Primitive, and Promisable, which help with defining literals, primitive values, and promise-like structures.
{"isPrimitive": true}
Basic utilities
Provides utility types such as Except, Mutable, ReadonlyDeep, and many others that help manipulate and transform types in various ways.
{"isEmptyArray": array.length === 0}
Object types
Contains types for working with objects, such as Merge and RequireAtLeastOne, which assist in merging types and ensuring at least one property is present, respectively.
{"isObjectClean": Object.keys(object).length === 0 && object.constructor === Object}
Conditional types
Includes conditional types like ConditionalExcept and ConditionalKeys, which apply conditions to filter keys or properties of types.
{"isTruthy": T extends false | '' | 0 | null | undefined ? false : true}
Other packages similar to type-fest
utility-types
The utility-types package provides a collection of utility types for TypeScript, similar to type-fest. It includes types for operations like picking, omitting, and readonly transformations. It is comparable to type-fest but may have a different set of utilities and slightly different implementations.
ts-essentials
ts-essentials offers a wide range of TypeScript types, including deep readonly and writable types, as well as utility types for better type inference. It is similar to type-fest in its goal to enhance TypeScript's type system but may differ in the specific types offered and its API design.
typesafe-actions
While typesafe-actions is more focused on Redux action creators, it also provides utility types for better type safety in Redux. It is similar to type-fest in that it enhances TypeScript's type system but is more specialized for Redux-related typing.
A collection of essential TypeScript types
Many of the types here should have been built-in. You can help by suggesting some of them to the TypeScript project.
Either add this package as a dependency or copy-paste the needed types. No credit required. 👌
PR welcome for additional commonly needed types and docs improvements. Read the contributing guidelines first.
Help wanted with reviewing proposals and pull requests.
Install
npm install type-fest
Requires TypeScript >=4.2
Usage
import type {Except} from 'type-fest';
type Foo = {
unicorn: string;
rainbow: boolean;
};
type FooWithoutRainbow = Except<Foo, 'rainbow'>;
API
Click the type names for complete docs.
Basic
Utilities
Except
- Create a type from an object type without certain keys. This is a stricter version of Omit
.Writable
- Create a type that strips readonly
from all or some of an object's keys. The inverse of Readonly<T>
. Formerly named Mutable
.Merge
- Merge two types into a new type. Keys of the second type overrides keys of the first type.MergeExclusive
- Create a type that has mutually exclusive keys.RequireAtLeastOne
- Create a type that requires at least one of the given keys.RequireExactlyOne
- Create a type that requires exactly a single key of the given keys and disallows more.RequireAllOrNone
- Create a type that requires all of the given keys or none of the given keys.RemoveIndexSignature
- Create a type that only has explicitly defined properties, absent of any index signatures.PartialDeep
- Create a deeply optional version of another type. Use Partial<T>
if you only need one level deep.PartialOnUndefinedDeep
- Create a deep version of another type where all keys accepting undefined
type are set to optional.ReadonlyDeep
- Create a deeply immutable version of an object
/Map
/Set
/Array
type. Use Readonly<T>
if you only need one level deep.LiteralUnion
- Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for Microsoft/TypeScript#29729.Opaque
- Create an opaque type.UnwrapOpaque
- Revert an opaque type back to its original type.InvariantOf
- Create an invariant type, which is a type that does not accept supertypes and subtypes.SetOptional
- Create a type that makes the given keys optional.SetRequired
- Create a type that makes the given keys required.SetNonNullable
- Create a type that makes the given keys non-nullable.ValueOf
- Create a union of the given object's values, and optionally specify which keys to get the values from.ConditionalKeys
- Extract keys from a shape where values extend the given Condition
type.ConditionalPick
- Like Pick
except it selects properties from a shape where the values extend the given Condition
type.ConditionalExcept
- Like Omit
except it removes properties from a shape where the values extend the given Condition
type.UnionToIntersection
- Convert a union type to an intersection type.LiteralToPrimitive
- Convert a literal type to the primitive type it belongs to.Stringified
- Create a type with the keys of the given type changed to string
type.IterableElement
- Get the element type of an Iterable
/AsyncIterable
. For example, an array or a generator.Entry
- Create a type that represents the type of an entry of a collection.Entries
- Create a type that represents the type of the entries of a collection.SetReturnType
- Create a function type with a return type of your choice and the same parameters as the given function type.Simplify
- Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.Get
- Get a deeply-nested property from an object using a key path, like Lodash's .get()
function.StringKeyOf
- Get keys of the given type as strings.Schema
- Create a deep version of another object type where property values are recursively replaced into a given value type.Exact
- Create a type that does not allow extra properties.OptionalKeysOf
- Extract all optional keys from the given type.HasOptionalKeys
- Create a true
/false
type depending on whether the given type has any optional fields.RequiredKeysOf
- Extract all required keys from the given type.HasRequiredKeys
- Create a true
/false
type depending on whether the given type has any required fields.Spread
- Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
JSON
Async
Promisable
- Create a type that represents either the value or the value wrapped in PromiseLike
.AsyncReturnType
- Unwrap the return type of a function that returns a Promise
.Asyncify
- Create an async version of the given function type.
String
Trim
- Remove leading and trailing spaces from a string.Split
- Represents an array of strings split using a given character or character set.Replace
- Represents a string with some or all matches replaced by a replacement.
Array
Includes
- Returns a boolean for whether the given array includes the given item.Join
- Join an array of strings and/or numbers using the given string as a delimiter.LastArrayElement
- Extracts the type of the last element of an array.FixedLengthArray
- Create a type that represents an array of the given type and length.MultidimensionalArray
- Create a type that represents a multidimensional array of the given type and dimensions.MultidimensionalReadonlyArray
- Create a type that represents a multidimensional readonly array of the given type and dimensions.ReadonlyTuple
- Create a type that represents a read-only tuple of the given type and length.
Numeric
Change case
Miscellaneous
Declined types
If we decline a type addition, we will make sure to document the better solution here.
Diff
and Spread
- The pull request author didn't provide any real-world use-cases and the PR went stale. If you think this type is useful, provide some real-world use-cases and we might reconsider.Dictionary
- You only save a few characters (Dictionary<number>
vs Record<string, number>
) from Record
, which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have Map
in JavaScript now.ExtractProperties
and ExtractMethods
- The types violate the single responsibility principle. Instead, refine your types into more granular type hierarchies.Url2Json
- Inferring search parameters from a URL string is a cute idea, but not very useful in practice, since search parameters are usually dynamic and defined separately.Nullish
- The type only saves a couple of characters, not everyone knows what "nullish" means, and I'm also trying to get away from null
.TitleCase
- It's not solving a common need and is a better fit for a separate package.ExtendOr
and ExtendAnd
- The benefits don't outweigh having to learn what they mean.PackageJsonExtras
- There are too many possible configurations that can be put into package.json
. If you would like to extend PackageJson
to support an additional configuration in your project, please see the Extending existing types section below.
Alternative type names
If you know one of our types by a different name, add it here for discovery.
Tips
Extending existing types
Related
Built-in types
There are many advanced types most users don't know about.
-
Partial<T>
- Make all properties in T
optional.
Example
Playground
interface NodeConfig {
appName: string;
port: number;
}
class NodeAppBuilder {
private configuration: NodeConfig = {
appName: 'NodeApp',
port: 3000
};
private updateConfig<Key extends keyof NodeConfig>(key: Key, value: NodeConfig[Key]) {
this.configuration[key] = value;
}
config(config: Partial<NodeConfig>) {
type NodeConfigKey = keyof NodeConfig;
for (const key of Object.keys(config) as NodeConfigKey[]) {
const updateValue = config[key];
if (updateValue === undefined) {
continue;
}
this.updateConfig(key, updateValue);
}
return this;
}
}
new NodeAppBuilder().config({appName: 'ToDoApp'});
-
Required<T>
- Make all properties in T
required.
Example
Playground
interface ContactForm {
email?: string;
message?: string;
}
function submitContactForm(formData: Required<ContactForm>) {
}
submitContactForm({
email: 'ex@mple.com',
message: 'Hi! Could you tell me more about…',
});
submitContactForm({
email: 'ex@mple.com',
});
-
Readonly<T>
- Make all properties in T
readonly.
Example
Playground
enum LogLevel {
Off,
Debug,
Error,
Fatal
};
interface LoggerConfig {
name: string;
level: LogLevel;
}
class Logger {
config: Readonly<LoggerConfig>;
constructor({name, level}: LoggerConfig) {
this.config = {name, level};
Object.freeze(this.config);
}
}
const config: LoggerConfig = {
name: 'MyApp',
level: LogLevel.Debug
};
const logger = new Logger(config);
logger.config.level = LogLevel.Error;
config.level = LogLevel.Error;
-
Pick<T, K>
- From T
, pick a set of properties whose keys are in the union K
.
Example
Playground
interface Article {
title: string;
thumbnail: string;
content: string;
}
type ArticlePreview = Pick<Article, 'title' | 'thumbnail'>;
function renderArticlePreviews(previews: ArticlePreview[]): HTMLElement {
const articles = document.createElement('div');
for (const preview of previews) {
}
return articles;
}
const articles = renderArticlePreviews([
{
title: 'TypeScript tutorial!',
thumbnail: '/assets/ts.jpg'
}
]);
-
Record<K, T>
- Construct a type with a set of properties K
of type T
.
Example
Playground
type MemberPosition = 'intern' | 'developer' | 'tech-lead';
interface Employee {
firstName: string;
lastName: string;
yearsOfExperience: number;
}
const team: Record<MemberPosition, Employee[]> = {
intern: [],
developer: [],
'tech-lead': [],
};
team.intern.push({
firstName: 'John',
lastName: 'Doe',
yearsOfExperience: 0
});
const teamEmpty: Record<MemberPosition, null> = {
intern: null,
developer: null,
};
-
Exclude<T, U>
- Exclude from T
those types that are assignable to U
.
Example
Playground
interface ServerConfig {
port: null | string | number;
}
type RequestHandler = (request: Request, response: Response) => void;
function getPortValue(port: Exclude<ServerConfig['port'], null>): number {
if (typeof port === 'string') {
return parseInt(port, 10);
}
return port;
}
function startServer(handler: RequestHandler, config: ServerConfig): void {
const server = require('http').createServer(handler);
const port = config.port === null ? 3000 : getPortValue(config.port);
server.listen(port);
}
-
Extract<T, U>
- Extract from T
those types that are assignable to U
.
Example
Playground
declare function uniqueId(): number;
const ID = Symbol('ID');
interface Person {
[ID]: number;
name: string;
age: number;
}
function changePersonData<
Obj extends Person,
Key extends Extract<keyof Person, string>,
Value extends Obj[Key]
> (obj: Obj, key: Key, value: Value): void {
obj[key] = value;
}
const andrew = {
[ID]: uniqueId(),
name: 'Andrew',
age: 0,
};
changePersonData(andrew, 'name', 'Pony');
changePersonData(andrew, ID, uniqueId());
-
NonNullable<T>
- Exclude null
and undefined
from T
.
Example
Works with strictNullChecks
set to true
.
Playground
type PortNumber = string | number | null;
class ServerBuilder {
portNumber!: NonNullable<PortNumber>;
port(this: ServerBuilder, port: PortNumber): ServerBuilder {
if (port == null) {
this.portNumber = 8000;
} else {
this.portNumber = port;
}
return this;
}
}
const serverBuilder = new ServerBuilder();
serverBuilder
.port('8000')
.port(null)
.port(3000);
serverBuilder.portNumber = null;
-
Parameters<T>
- Obtain the parameters of a function type in a tuple.
Example
Playground
function shuffle(input: any[]): void {
}
function callNTimes<Fn extends (...args: any[]) => any> (func: Fn, callCount: number) {
type FunctionParameters = Parameters<Fn>;
return function (...args: FunctionParameters) {
for (let i = 0; i < callCount; i++) {
func(...args);
}
}
}
const shuffleTwice = callNTimes(shuffle, 2);
-
ConstructorParameters<T>
- Obtain the parameters of a constructor function type in a tuple.
Example
Playground
class ArticleModel {
title: string;
content?: string;
constructor(title: string) {
this.title = title;
}
}
class InstanceCache<T extends (new (...args: any[]) => any)> {
private ClassConstructor: T;
private cache: Map<string, InstanceType<T>> = new Map();
constructor (ctr: T) {
this.ClassConstructor = ctr;
}
getInstance (...args: ConstructorParameters<T>): InstanceType<T> {
const hash = this.calculateArgumentsHash(...args);
const existingInstance = this.cache.get(hash);
if (existingInstance !== undefined) {
return existingInstance;
}
return new this.ClassConstructor(...args);
}
private calculateArgumentsHash(...args: any[]): string {
return 'hash';
}
}
const articleCache = new InstanceCache(ArticleModel);
const amazonArticle = articleCache.getInstance('Amazon forests burining!');
-
ReturnType<T>
- Obtain the return type of a function type.
Example
Playground
function mapIter<
Elem,
Func extends (elem: Elem) => any,
Ret extends ReturnType<Func>
>(iter: Iterable<Elem>, callback: Func): Ret[] {
const mapped: Ret[] = [];
for (const elem of iter) {
mapped.push(callback(elem));
}
return mapped;
}
const setObject: Set<string> = new Set();
const mapObject: Map<number, string> = new Map();
mapIter(setObject, (value: string) => value.indexOf('Foo'));
mapIter(mapObject, ([key, value]: [number, string]) => {
return key % 2 === 0 ? value : 'Odd';
});
-
InstanceType<T>
- Obtain the instance type of a constructor function type.
Example
Playground
class IdleService {
doNothing (): void {}
}
class News {
title: string;
content: string;
constructor(title: string, content: string) {
this.title = title;
this.content = content;
}
}
const instanceCounter: Map<Function, number> = new Map();
interface Constructor {
new(...args: any[]): any;
}
function getInstance<
Constr extends Constructor,
Args extends ConstructorParameters<Constr>
>(constructor: Constr, ...args: Args): InstanceType<Constr> {
let count = instanceCounter.get(constructor) || 0;
const instance = new constructor(...args);
instanceCounter.set(constructor, count + 1);
console.log(`Created ${count + 1} instances of ${Constr.name} class`);
return instance;
}
const idleService = getInstance(IdleService);
const newsEntry = getInstance(News, 'New ECMAScript proposals!', 'Last month...');
-
Omit<T, K>
- Constructs a type by picking all properties from T and then removing K.
Example
Playground
interface Animal {
imageUrl: string;
species: string;
images: string[];
paragraphs: string[];
}
type AnimalShortInfo = Omit<Animal, 'images' | 'paragraphs'>;
function renderAnimalHoverInfo (animals: AnimalShortInfo[]): HTMLElement {
const container = document.createElement('div');
return container;
}
-
Uppercase<S extends string>
- Transforms every character in a string into uppercase.
Example
type T = Uppercase<'hello'>;
type T2 = Uppercase<'foo' | 'bar'>;
type T3<S extends string> = Uppercase<`aB${S}`>;
type T4 = T3<'xYz'>;
type T5 = Uppercase<string>;
type T6 = Uppercase<any>;
type T7 = Uppercase<never>;
type T8 = Uppercase<42>;
-
Lowercase<S extends string>
- Transforms every character in a string into lowercase.
Example
type T = Lowercase<'HELLO'>;
type T2 = Lowercase<'FOO' | 'BAR'>;
type T3<S extends string> = Lowercase<`aB${S}`>;
type T4 = T3<'xYz'>;
type T5 = Lowercase<string>;
type T6 = Lowercase<any>;
type T7 = Lowercase<never>;
type T8 = Lowercase<42>;
-
Capitalize<S extends string>
- Transforms the first character in a string into uppercase.
Example
type T = Capitalize<'hello'>;
type T2 = Capitalize<'foo' | 'bar'>;
type T3<S extends string> = Capitalize<`aB${S}`>;
type T4 = T3<'xYz'>;
type T5 = Capitalize<string>;
type T6 = Capitalize<any>;
type T7 = Capitalize<never>;
type T8 = Capitalize<42>;
-
Uncapitalize<S extends string>
- Transforms the first character in a string into lowercase.
Example
type T = Uncapitalize<'Hello'>;
type T2 = Uncapitalize<'Foo' | 'Bar'>;
type T3<S extends string> = Uncapitalize<`AB${S}`>;
type T4 = T3<'xYz'>;
type T5 = Uncapitalize<string>;
type T6 = Uncapitalize<any>;
type T7 = Uncapitalize<never>;
type T8 = Uncapitalize<42>;
You can find some examples in the TypeScript docs.
Maintainers
License
SPDX-License-Identifier: (MIT OR CC0-1.0)